prosemirror 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c84fca02d8a8c1f32c9162da3a22133f2ef774c035281331d7d92423d24a242f
-  data.tar.gz: ca2ec139725747838a359f43a667c1fc4b5b5249b7dba12775ffbe39985f0c38
+  metadata.gz: 8aae1987528266c7bd7c4b3c3d8f7c82e74f74cf89ee9e7ac87b1732ff76634d
+  data.tar.gz: d5cb877b264eb0d39cd40cd8b4909ec94b423ac439a6719df23c70eb6cde6182
 SHA512:
-  metadata.gz: c018119a21927872e1382b1ee05f33c397781c87520b55ee4ca76f06abc2fb728ed4122043f11250cd3f8195c5ede8de4e50619bf98f93405f163fa30bd413aa
-  data.tar.gz: 3a870e5aceacd20c1ec717942f3dc4c75a97f811e8813e73c346aa71b919ab4430645593c6daec6132a1c72cd3f053e192ff812126cf22cd8f567cc5cafb8b98
+  metadata.gz: 947eab5fdc041f059be90be81b94bc66bb1505118b983ed982100faf1ccf2748fdcf753f83384385af72e80cc610473e24eeca31aa6a404ed93f431a8d3138d2
+  data.tar.gz: 4a56748f16cc7ac1af9ad1660518870dfded5f22b089e714417cf74afb970e0ec8b9f53d2d9e1adc82662efac63c449ba1dff10d07988ed8ca110413143c2452

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-24
+
+- Tiptap's YouTube and Twitch embeds, in `Schema.tiptap`: `youtube` and `twitch`, with the video's URL in `src`, rendered as an iframe of its embed URL, built from the video's id. They are imported from Tiptap's markup, and from iframes of embed URLs without it. Subclasses set Twitch's `parent` domain and YouTube's nocookie host. Markdown export writes a link to the video, or the iframe with `html: true`.
+- Tiptap's details, in `Schema.tiptap`: `details`, `details_summary` and `details_content`, rendered and imported as Tiptap does, including `<details>` without Tiptap's content wrapper. `open`, which Tiptap keeps with `persist: true`, is rendered and imported. Markdown export writes them as `<details>` HTML around Markdown content, as GitHub reads it.
+- `Schema.tiptap(text_align: true)` adds Tiptap's TextAlign extension to headings and paragraphs: a `textAlign` attribute, rendered as a `text-align` style, and imported from it or from the old `align` attribute. Other types get it by including `Prosemirror::TextAlign`.
+- Tiptap's task lists, in `Schema.tiptap`: `task_list` and `task_item`, with a `checked` attribute. They render Tiptap's HTML, and are imported from it and from GitHub's. Markdown import reads GitHub Flavored Markdown task lists: a bullet list whose items all have a checkbox is a task list, and other checkboxes stay as text. Markdown export writes `- [x]` items.
+- Tiptap's mention node, in `Schema.tiptap`: rendered as `<span data-type="mention">@label</span>`, with its `id`, `label` and `mentionSuggestionChar` in `data-` attributes, and imported from that HTML. Its text is `@label`, or `@id` without a label. In Markdown, it's written as text, or as HTML with `html: true`.
+
+## [0.5.0] - 2026-10-24
+
+- `Document#to_markdown` writes Markdown, with GitHub Flavored Markdown tables and strikethrough, like prosemirror-markdown. Node types write themselves in `to_markdown`, and mark types declare their syntax with `markdown`. `html: true` writes underline, highlight, subscript, superscript and image sizes as HTML.
+- `Document#check` accepts attributes whose JSON name differs from their property name, like a link's `class`. It reported them as invalid.
+- Faster: parsing JSON takes less than half the time, rendering and `to_h` about a third less, and HTML and Markdown import about a quarter less, with the same results. Strings in documents parsed from a JSON string are frozen, including the values of unknown attributes.
+
 ## [0.4.0] - 2026-10-24
 
 - `Document#transform` builds a new document from a block called with each node, children first, which keeps, replaces, removes or splices nodes. Required content that goes missing is added back and reported.

data/README.md

@@ -24,6 +24,7 @@ doc = Prosemirror.parse(record.content)  # a Hash or a JSON string
 
 doc.to_html  # => "<h2>Hello</h2><p>World</p>"
 doc.to_text  # => "Hello\n\nWorld"
+doc.to_markdown  # => "## Hello\n\nWorld\n"
 doc.to_h     # => { "type" => "doc", "content" => [...] }
 ```
 
@@ -108,15 +109,34 @@ bundle add commonmarker
 doc = Prosemirror.from_markdown("## Hello\n\nSome **bold** text.")
 ```
 
-It reads GitHub Flavored Markdown: tables, strikethrough and autolinks. Each Markdown node becomes the element commonmarker renders for it, and the schema's parse rules apply as in HTML import, so custom types can match Markdown too: a type that matches `img` also gets Markdown images. For the built-in types, it gives the same JSON as rendering the Markdown to HTML and importing it in Tiptap, except that:
+It reads GitHub Flavored Markdown: tables, strikethrough, autolinks and task lists. Each Markdown node becomes the element commonmarker renders for it, and the schema's parse rules apply as in HTML import, so custom types can match Markdown too: a type that matches `img` also gets Markdown images. For the built-in types, it gives the same JSON as rendering the Markdown to HTML and importing it in Tiptap, except that:
 
 - code blocks lose their final newline, as in prosemirror-markdown;
-- task list items (`- [ ] todo`) stay as list items starting with `[ ] ` or `[x] `.
+- a bullet list whose items all have a checkbox (`- [ ] todo`) is a task list. In other lists, which Tiptap's task lists can't hold, checkboxes stay as text at the start of their item: `[ ] ` or `[x] `.
 
 Raw HTML in Markdown goes through HTML import when the herb gem is installed, and stays as text otherwise.
 
 YAML front matter, between `---` lines at the start, is dropped. Footnotes aren't supported yet: `[^1]: Note` reads as a link definition, as in CommonMark. Markdown nested more than 1,000 levels deep raises `Prosemirror::Error`.
 
+## Markdown export
+
+`to_markdown` writes the document as Markdown, with GitHub Flavored Markdown for tables, strikethrough and task lists, like [prosemirror-markdown](https://github.com/ProseMirror/prosemirror-markdown). It needs no gem.
+
+```ruby
+doc.to_markdown              # => "## Hello\n\n**World**\n"
+doc.to_markdown(html: true)  # underline, highlight, subscript, superscript and mentions as HTML
+```
+
+- Text is escaped, so that it reads back as text: `*`, `_`, `[`, a `#` or `-` that would start a block, HTML-like `<b>`, and URLs that GitHub would turn into links.
+- Markdown has no syntax for underline, highlight, subscript, superscript, image sizes or mentions: by default, only their text or image is written, like `@Ada` for a mention. With `html: true`, they are written as HTML.
+- Emphasis that CommonMark can't write where it is, like bold on a comma between two letters, is dropped and its text kept.
+- Tables are written as GFM tables. A cell's paragraphs and line breaks are joined with `<br>`, and its other blocks, like lists, are written as HTML.
+- Details are written as `<details>` HTML, as on GitHub, with their content in Markdown.
+- YouTube and Twitch embeds are written as links to the video. With `html: true`, they are written as their iframe.
+- Empty paragraphs are left out.
+
+Importing the Markdown gives the document back, as far as Markdown can hold it. Custom types write their own Markdown: see [Node and mark types](TYPES.md#markdown-export).
+
 ## Text import
 
 ```ruby
@@ -130,8 +150,13 @@ Blank lines separate paragraphs, and other line breaks become hard breaks. Space
 Two schemas are included:
 
 ```ruby
-Prosemirror::Schema.tiptap       # Tiptap's StarterKit, tables, images, underline, subscript, superscript, highlight (default)
-Prosemirror::Schema.prosemirror  # prosemirror-schema-basic and prosemirror-schema-list
+# The default: Tiptap's StarterKit, with tables, images, task lists,
+# details, YouTube and Twitch embeds, mentions, underline, subscript,
+# superscript and highlight
+Prosemirror::Schema.tiptap
+
+# prosemirror-schema-basic and prosemirror-schema-list
+Prosemirror::Schema.prosemirror
 ```
 
 Type names are written in snake_case (`bullet_list`). Use `case: :camel` to write camelCase (`bulletList`), as Tiptap does. Both cases are always accepted on input.
@@ -140,6 +165,26 @@ Type names are written in snake_case (`bullet_list`). Use `case: :camel` to writ
 Prosemirror.schema = Prosemirror::Schema.tiptap(case: :camel)
 ```
 
+`text_align: true` adds Tiptap's TextAlign extension, configured for headings and paragraphs: a `textAlign` attribute, `left`, `center`, `right` or `justify`, rendered as a `text-align` style. HTML import also reads the old `align` attribute. Markdown has no syntax for it: Markdown export leaves it out. Without the option, `textAlign` is kept in `to_h`, but not rendered.
+
+```ruby
+Prosemirror::Schema.tiptap(text_align: true)
+```
+
+YouTube and Twitch embeds store the video's URL in `src`, and render an iframe of its embed URL, built from the video's id: other URLs render nothing. HTML import reads Tiptap's markup, and also iframes of embed URLs without it. Twitch only plays embeds on the domain they name, so set it in a subclass, as Tiptap's `parent` option. YouTube's `nocookie` option is a subclass too:
+
+```ruby
+class Twitch < Prosemirror::Nodes::Twitch
+  def parent = "example.com"
+end
+
+class Youtube < Prosemirror::Nodes::Youtube
+  def embed_host = "https://www.youtube-nocookie.com"
+end
+
+Prosemirror.schema = Prosemirror::Schema.tiptap.with(Twitch, Youtube)
+```
+
 ## Custom nodes and marks
 
 A node type is a Phlex component, and its attributes are Literal properties. The type name comes from the class name (`ImageBlock` → `image_block`).

data/ROADMAP.md

@@ -192,14 +192,18 @@ They differ in more than names:
   ```
 - Validation against the schema (`check`).
 
-### 0.5: Markdown export
+### 0.5: Markdown export (released)
 
-- `doc.to_markdown`, like [`prosemirror-markdown`](https://github.com/ProseMirror/prosemirror-markdown). Useful to send content to LLMs.
-- Help wanted: it is self-contained and a good first contribution.
+- `doc.to_markdown`, ported from [`prosemirror-markdown`](https://github.com/ProseMirror/prosemirror-markdown)'s serializer. Useful to send content to LLMs.
+- GitHub Flavored Markdown tables and strikethrough. Formatting without Markdown syntax, like underline, keeps its text, or is written as HTML with `html: true`.
+- Custom node types write themselves in `to_markdown`, and mark types declare their syntax with `markdown`.
+- Importing the Markdown gives the document back, as far as Markdown can hold it, tested on real-world Markdown and HTML.
 
-### 0.6: More Tiptap node types
+### 0.6: More Tiptap node types (released)
 
-- Task lists, text alignment, mentions, details, embeds.
+- Mentions, task lists, details, and YouTube and Twitch embeds, in `Schema.tiptap`, with HTML that gives the same JSON as Tiptap's `generateJSON`.
+- Text alignment, as an option: `Schema.tiptap(text_align: true)`.
+- GitHub Flavored Markdown task lists in Markdown import and export. Details are written as GitHub's `<details>` HTML.
 
 ### 1.0
 

data/TYPES.md

@@ -27,6 +27,7 @@ A type is a [Phlex](https://www.phlex.fun) component, and its attributes are [Li
 - [Rendering](#rendering)
 - [Parse rules](#parse-rules)
 - [Markdown](#markdown)
+- [Markdown export](#markdown-export)
 - [Subclassing built-in types](#subclassing-built-in-types)
 
 ## Names
@@ -203,6 +204,48 @@ Markdown import builds the elements commonmarker renders for each Markdown node,
 
 Raw HTML in Markdown goes through HTML import when the herb gem is installed, and stays as text otherwise.
 
+## Markdown export
+
+A node type writes itself in `to_markdown`, with the methods of `Prosemirror::MarkdownSerializer`, ported from prosemirror-markdown's `MarkdownSerializerState`. As in `view_template`, attributes are instance variables, and `node` is the node:
+
+```ruby
+class Callout < Prosemirror::NodeType
+  def to_markdown(markdown, parent, index)
+    markdown.wrap_block("> ", "> **Note:** ", node) { markdown.render_content(node) }
+  end
+end
+```
+
+| Method | Does |
+|---|---|
+| `write(text)` | Writes text as it is, after closing the previous block. |
+| `text(text, escape: true)` | Writes text, escaped. |
+| `render_inline(node)` | Writes the node's inline content, with its marks. |
+| `render_content(node)` | Writes the node's blocks. |
+| `wrap_block(delim, first_delim, node) { … }` | Writes a block with each line prefixed, like `> `. |
+| `render_list(node, delim) { \|index\| marker }` | Writes a list. |
+| `close_block(node)` | Ends the block: the next one starts after a blank line. |
+| `esc(text)`, `url(href)`, `node_html(node)`, `html?` | Escaping, a link destination, a node's HTML, and whether `html: true` was given. |
+
+Without `to_markdown`, a type writes its content.
+
+A mark type declares its syntax with `markdown`, as prosemirror-markdown's mark specs:
+
+```ruby
+class Keyboard < Prosemirror::MarkType
+  markdown open: "<kbd>", close: "</kbd>", escape: false
+end
+```
+
+| Option | Meaning |
+|---|---|
+| `open`, `close` | Strings, or blocks called with the serializer, the mark, the parent node and the index of the marked node. |
+| `mixable: true` | The mark can open and close in any order with other mixable marks, like `*` and `**`. |
+| `expel_enclosing_whitespace: true` | Spaces at the edges move outside the mark, as emphasis requires. |
+| `escape: false` | The content isn't escaped, as in inline code. The mark must come last. |
+
+Without `markdown`, a mark writes its text, or its HTML with `to_markdown(html: true)`.
+
 ## Subclassing built-in types
 
 A subclass keeps the name, options, attributes and parse rules of its parent, and can change any of them. Register it with `Schema#with`, which replaces the built-in type with the same name:
@@ -216,3 +259,15 @@ Prosemirror.schema = Prosemirror::Schema.tiptap.with(Paragraph)
 ```
 
 A subclass that declares parse rules replaces the rules of its parent. See the [cookbook](COOKBOOK.md) for more examples.
+
+With `Schema.tiptap(text_align: true)`, paragraphs and headings are `Prosemirror::TextAlign::Paragraph` and `Prosemirror::TextAlign::Heading`: subclass these to keep the alignment. Other types get it by including `Prosemirror::TextAlign`, which declares the `text_align` attribute, and rendering `text_align_style`:
+
+```ruby
+class Callout < Prosemirror::NodeType
+  include Prosemirror::TextAlign
+  group :block
+  content "inline*"
+
+  def view_template(&) = aside(style: text_align_style, &)
+end
+```

data/lib/prosemirror/checker.rb

@@ -63,10 +63,10 @@ module Prosemirror
       invalid("invalid marks: #{node.marks.map { |mark| @schema.json_type_name(mark.type) }.join(" ")}", path) unless sorted == node.marks
     end
 
-    # Attributes are valid when building them from themselves reports nothing and changes nothing.
+    # Attributes are valid when building them from their JSON reports nothing and changes nothing.
     def check_attrs(type, attrs, path)
       problems = []
-      built = type.build_attrs(attrs, report: ->(message) { problems << message })
+      built = type.build_attrs(type.serialize_attrs(attrs), report: ->(message) { problems << message })
       invalid(problems.first, path) unless problems.empty?
       invalid("invalid attributes: #{attrs.inspect}", path) unless built == attrs
     end

data/lib/prosemirror/coerce.rb

@@ -13,5 +13,12 @@ module Prosemirror
 
     # A frozen copy, unless the value is already frozen.
     FROZEN = proc { |value| value.frozen? ? value : value.dup.freeze }
+
+    # The coercions above, which don't use `self`.
+    PLAIN = [INTEGER, SYMBOL, FROZEN].freeze
+
+    def self.frozen(value)
+      value.frozen? ? value : value.dup.freeze
+    end
   end
 end

data/lib/prosemirror/document.rb

@@ -47,6 +47,12 @@ module Prosemirror
       TextSerializer.new(schema, block_separator: block_separator).call(root)
     end
 
+    # The document as Markdown (GitHub Flavored Markdown for tables and strikethrough). Formatting Markdown
+    # has no syntax for, like underline, keeps only its text, or is written as HTML with `html: true`.
+    def to_markdown(html: false)
+      MarkdownSerializer.new(schema, html: html).call(root)
+    end
+
     # The document as JSON, as a Hash.
     def to_h
       schema.serialize(root)

data/lib/prosemirror/html/element.rb

@@ -33,7 +33,7 @@ module Prosemirror
       end
 
       def classes
-        self["class"].to_s.split
+        @classes ||= self["class"].to_s.split.freeze
       end
 
       # The declarations of the `style` attribute, with lowercase properties: `{"font-weight" => "bold"}`.

data/lib/prosemirror/html/selector.rb

@@ -15,22 +15,30 @@ module Prosemirror
 
       def initialize(source)
         @source = source
-        @compounds = source.split(",").map { |part| parse_compound(part.strip) }
+        @names = []
+        @compounds = source.split(",").map { |part| parse_compound(part.strip, top: true) }
+        @names = @names.include?(nil) ? nil : @names.uniq.freeze
       end
 
       def match?(element)
         @compounds.any? { |tests| tests.all? { |test| test.call(element) } }
       end
 
+      # The element names it can match, or nil when it can match any element.
+      attr_reader :names
+
       private
 
-      def parse_compound(part)
+      def parse_compound(part, top: false)
         invalid! if part.empty?
 
         tests = []
         rest = part
-        if (type = rest[/\A(?:\*|#{IDENTIFIER})/o])
-          tests << ->(element) { element.name == type.downcase } unless type == "*"
+        type = rest[/\A(?:\*|#{IDENTIFIER})/o]
+        name = type.downcase.freeze if type && type != "*"
+        @names << name if top
+        if type
+          tests << ->(element) { element.name == name } if name
           rest = rest[type.length..]
         end
         until rest.empty?

data/lib/prosemirror/html_parser.rb

@@ -34,6 +34,11 @@ module Prosemirror
       rules = (schema.marks + schema.nodes).flat_map(&:parse_rules)
       rules = rules.each_with_index.sort_by { |rule, index| [-rule.priority, index] }.map(&:first)
       @tags = rules.select(&:tag)
+      @selectors = @tags.map { |rule| HTML::Selector.parse(rule.tag) }
+      # The indexes of the tag rules that can match an element with this name, in order.
+      @candidates = Hash.new do |candidates, name|
+        candidates[name] = @selectors.each_index.select { |index| @selectors[index].names.nil? || @selectors[index].names.include?(name) }.freeze
+      end
       @styles = rules.select(&:style)
       @matched_styles = @styles.map(&:style_property).uniq
       @normalize_lists = @tags.none? { |rule| lists_contain_themselves?(rule) }
@@ -53,9 +58,11 @@ module Prosemirror
 
     # The first tag rule after `after` that matches the element in this context.
     def match_tag(element, context, after = nil)
-      ((after ? after + 1 : 0)...@tags.size).each do |index|
+      @candidates[element.name].each do |index|
+        next if after && index <= after
+
         rule = @tags[index]
-        next unless HTML::Selector.parse(rule.tag).match?(element)
+        next unless @selectors[index].match?(element)
         next if rule.context && !context.matches_context?(rule.context)
 
         match = build_match(rule, index, element) { |get_attrs| call_get_attrs(get_attrs, element) }

data/lib/prosemirror/json_parser.rb

@@ -6,19 +6,26 @@ module Prosemirror
   # Invalid parts are fixed and reported to the schema (which raises in strict mode).
   class JSONParser
     MAX_DEPTH = 100
+    EMPTY = [].freeze
 
     def initialize(schema)
       @schema = schema
+      # The path of the node being built, as `["doc", :content, 0, :marks, 1]`: a string is only made for
+      # a report.
+      @path = []
+      @report = ->(message) { invalid(message) }
     end
 
     def parse(json)
-      hash = json.is_a?(String) ? JSON.parse(json, max_nesting: (MAX_DEPTH * 2) + 2) : json
+      # Frozen strings go into nodes without being copied.
+      hash = json.is_a?(String) ? JSON.parse(json, max_nesting: (MAX_DEPTH * 2) + 2, freeze: true) : json
       raise ArgumentError, "expected a Hash or a JSON String, got #{json.class}" unless hash.is_a?(Hash)
 
-      root = build_node(hash, "doc", 0) || Node.new(type: @schema.top_node)
+      @path = ["doc"]
+      root = build_node(hash, 0) || Node.new(type: @schema.top_node)
       return root if root.type == @schema.top_node
 
-      @schema.report("the top node is #{root.type}, not #{@schema.top_node}", path: "doc")
+      invalid("the top node is #{root.type}, not #{@schema.top_node}")
       Node.new(type: @schema.top_node, content: [root])
     rescue JSON::NestingError
       raise InvalidDocument, "the document is nested more than #{MAX_DEPTH} levels deep"
@@ -26,88 +33,112 @@ module Prosemirror
 
     private
 
-    def build_node(hash, path, depth)
-      return invalid("not a node: #{hash.inspect}", path) unless hash.is_a?(Hash)
-      return invalid("nested more than #{MAX_DEPTH} levels deep", path) if depth > MAX_DEPTH
+    def build_node(hash, depth)
+      return invalid("not a node: #{hash.inspect}") unless hash.is_a?(Hash)
+      return invalid("nested more than #{MAX_DEPTH} levels deep") if depth > MAX_DEPTH
 
       name = fetch(hash, "type")
-      return invalid("missing node type", path) unless name.is_a?(String) || name.is_a?(Symbol)
-      return build_text(hash, path) if name.to_s == "text"
+      return invalid("missing node type") unless name.is_a?(String) || name.is_a?(Symbol)
+      return build_text(hash) if name == "text" || name == :text
 
       node_type = @schema.node_type(name)
-      return build_unknown(hash, name, path, depth) unless node_type
+      return build_unknown(hash, name, depth) unless node_type
 
       given = fetch(hash, "attrs")
-      attrs = node_type.build_attrs(given, report: reporter(path))
-      return invalid("removed #{name} node", path) unless attrs
+      attrs = node_type.build_attrs(given, report: @report)
+      return invalid("removed #{name} node") unless attrs
 
-      Node.new(type: node_type.type_name, attrs: attrs, unknown_attrs: node_type.unknown_attrs(given),
-        content: build_content(hash, path, depth), marks: build_marks(fetch(hash, "marks"), path))
+      Node.new(type: node_type.type_name, attrs: attrs.freeze, unknown_attrs: node_type.unknown_attrs(given).freeze,
+        content: build_content(hash, depth), marks: build_marks(fetch(hash, "marks")))
     end
 
-    def build_text(hash, path)
+    def build_text(hash)
       text = fetch(hash, "text")
-      return invalid("text node without text", path) unless text.is_a?(String)
+      return invalid("text node without text") unless text.is_a?(String)
       return nil if text.empty?
 
-      Node.new(type: :text, text: text, marks: build_marks(fetch(hash, "marks"), path))
+      Node.new(type: :text, text: text, marks: build_marks(fetch(hash, "marks")))
     end
 
-    def build_unknown(hash, name, path, depth)
-      invalid("unknown node type #{name}", path)
+    def build_unknown(hash, name, depth)
+      invalid("unknown node type #{name}")
       attrs = fetch(hash, "attrs")
       Node.new(type: Naming.snake(name), attrs: attrs.is_a?(Hash) ? attrs.transform_keys(&:to_sym) : {},
-        content: build_content(hash, path, depth), marks: build_marks(fetch(hash, "marks"), path))
+        content: build_content(hash, depth), marks: build_marks(fetch(hash, "marks")))
     end
 
-    def build_content(hash, path, depth)
+    def build_content(hash, depth)
       content = fetch(hash, "content")
-      return [] if content.nil?
-      return invalid("content is not a list", path) || [] unless content.is_a?(Array)
+      return EMPTY if content.nil?
+      return invalid("content is not a list") || EMPTY unless content.is_a?(Array)
+
+      nodes = []
+      content.each_with_index do |child, index|
+        @path.push(:content, index)
+        node = build_node(child, depth + 1)
+        @path.pop
+        @path.pop
+        nodes << node if node
+      end
+      Node.join_text(nodes).freeze
+    end
 
-      nodes = content.each_with_index.filter_map do |child, index|
-        build_node(child, "#{path}.content[#{index}]", depth + 1)
+    def build_marks(marks)
+      return EMPTY if marks.nil?
+      return invalid("marks is not a list") || EMPTY unless marks.is_a?(Array)
+
+      built = []
+      marks.each_with_index do |mark, index|
+        @path.push(:marks, index)
+        mark = build_mark(mark)
+        @path.pop
+        @path.pop
+        built << mark if mark
       end
-      Node.join_text(nodes)
+      sort_marks(built).freeze
     end
 
-    def build_marks(marks, path)
-      return [] if marks.nil?
-      return invalid("marks is not a list", path) || [] unless marks.is_a?(Array)
+    # The marks without duplicates, in schema order. Most sets have one mark, or are already sorted.
+    def sort_marks(marks)
+      return marks if marks.size < 2
+
+      marks = marks.uniq
+      ranks = marks.map { |mark| @schema.mark_rank(mark.type) }
+      return marks if ranks.each_cons(2).all? { |a, b| a <= b }
 
-      built = marks.each_with_index.filter_map { |mark, index| build_mark(mark, "#{path}.marks[#{index}]") }
-      built.uniq.sort_by.with_index { |mark, index| [@schema.mark_rank(mark.type), index] }
+      marks.each_with_index.sort_by { |mark, index| [ranks[index], index] }.map(&:first)
     end
 
-    def build_mark(hash, path)
-      return invalid("not a mark: #{hash.inspect}", path) unless hash.is_a?(Hash)
+    def build_mark(hash)
+      return invalid("not a mark: #{hash.inspect}") unless hash.is_a?(Hash)
 
       name = fetch(hash, "type")
-      return invalid("missing mark type", path) unless name.is_a?(String) || name.is_a?(Symbol)
+      return invalid("missing mark type") unless name.is_a?(String) || name.is_a?(Symbol)
 
       mark_type = @schema.mark_type(name)
       unless mark_type
-        invalid("unknown mark type #{name}", path)
+        invalid("unknown mark type #{name}")
         attrs = fetch(hash, "attrs")
         return Mark.new(type: Naming.snake(name), attrs: attrs.is_a?(Hash) ? attrs.transform_keys(&:to_sym) : {})
       end
 
       given = fetch(hash, "attrs")
-      attrs = mark_type.build_attrs(given, report: reporter(path))
-      return invalid("removed #{name} mark", path) unless attrs
+      attrs = mark_type.build_attrs(given, report: @report)
+      return invalid("removed #{name} mark") unless attrs
 
-      Mark.new(type: mark_type.type_name, attrs: attrs, unknown_attrs: mark_type.unknown_attrs(given))
+      Mark.new(type: mark_type.type_name, attrs: attrs.freeze, unknown_attrs: mark_type.unknown_attrs(given).freeze)
     end
 
     def fetch(hash, key)
       hash.key?(key) ? hash[key] : hash[key.to_sym]
     end
 
-    def reporter(path)
-      ->(message) { @schema.report(message, path: path) }
+    # The path as written in reports: `doc.content[0].marks[1]`.
+    def path
+      ([@path.first] + @path.drop(1).each_slice(2).map { |name, index| "#{name}[#{index}]" }).join(".")
     end
 
-    def invalid(message, path)
+    def invalid(message)
       @schema.report(message, path: path)
     end
   end

data/lib/prosemirror/mark.rb

@@ -7,9 +7,14 @@ module Prosemirror
   #
   # As for nodes, `unknown_attrs` holds the attributes the mark's type doesn't declare.
   class Mark < Literal::Data
-    prop :type, Symbol, &Coerce::SYMBOL
-    prop :attrs, _Hash(Symbol, _Any?), default: {}.freeze, &Coerce::FROZEN
-    prop :unknown_attrs, _Hash(String, _Any?), default: {}.freeze, &Coerce::FROZEN
+    prop :type, Symbol
+    prop :attrs, _Hash(Symbol, _Any?), default: Node::EMPTY_HASH
+    prop :unknown_attrs, _Hash(String, _Any?), default: Node::EMPTY_HASH
+
+    # As Node#initialize.
+    def initialize(type:, attrs: Node::EMPTY_HASH, unknown_attrs: Node::EMPTY_HASH)
+      super(type: type.is_a?(String) ? type.to_sym : type, attrs: Coerce.frozen(attrs), unknown_attrs: Coerce.frozen(unknown_attrs))
+    end
 
     # A copy with some properties changed.
     def with(**changes)

data/lib/prosemirror/mark_type.rb

@@ -44,6 +44,21 @@ module Prosemirror
         inherited_setting(:@group, [])
       end
 
+      # The mark's Markdown syntax, as prosemirror-markdown's MarkSerializerSpec:
+      # - `open` and `close`: strings, or blocks called with the MarkdownSerializer, the mark, the parent node
+      #   and the index of the marked node;
+      # - `mixable`: the mark can open and close in any order with other mixable marks, like `*` and `**`;
+      # - `expel_enclosing_whitespace`: spaces at the edges move outside the mark, as emphasis requires;
+      # - `escape: false`: the content isn't escaped, as in inline code. The mark must come last.
+      # Without it, the mark keeps only its text, or its HTML with `to_markdown(html: true)`.
+      def markdown(open:, close:, mixable: false, expel_enclosing_whitespace: false, escape: true)
+        @markdown_spec = {open:, close:, mixable:, expel_enclosing_whitespace:, escape:}.freeze
+      end
+
+      def markdown_spec
+        inherited_setting(:@markdown_spec, nil)
+      end
+
       # Whether one element can wrap several adjacent nodes with this mark. Defaults to true.
       def spanning(value = nil)
         return @spanning = value unless value.nil?